Cream of the Crop 25

home *** CD-ROM | disk | FTP | other *** search

/ Cream of the Crop 25 / Cream of the Crop 25.iso / os2 / faxd_07.zip / RXIPC.ZIP / REXXIPC.INF (.txt) < prev next >

Wrap

OS/2 Help File | 1995-06-24 | 46KB | 2,374 lines

ΓòÉΓòÉΓòÉ 1. Copyright (c) Serge Brisson 1994, 1995 ΓòÉΓòÉΓòÉ Copyright (c) Serge Brisson 1994, 1995. All rights reserved. Distribution The copyright owner allows the free distribution of the following files, as long as they are kept together, unmodified: o REXXIPC.DLL -- The library. o REXXIPC.INF -- The documentation. o REXXIPC.TXT -- Distribution text. ΓòÉΓòÉΓòÉ 2. Introduction ΓòÉΓòÉΓòÉ The RexxIPC library is designed to supply basic Inter Process Communication capabilities for Rexx programs. This is accomplished by supplying a near one-to-one API to the Named Pipe, Event Semaphore, Mutex Semaphore and MuxWait Semaphore OS/2 system services. The design requirements for this library specified support of multi-threaded Rexx applications, support of access to the same IPC services by other C or C++ functions, simplicity of use and non-interference in the application's design. Since the underlying system services already meet these requirements, the library's design is mostly a straightforward Rexx interface to these services. This document is supplied as a reference to this interface. It assumes that the reader has access to the Control Program Guide and Reference from the Developer's Toolkit for OS/2. Note: The explicit use of system handles in the Pipe interface allows the access to multiple instances of the same pipe (useful in a multi-threaded environment). The explicit use of system handles in the Semaphore interface allows the use of unnamed semaphores. ΓòÉΓòÉΓòÉ 3. IPC Procedures and Functions ΓòÉΓòÉΓòÉ The IPC prefix identifies a few generic routines related to the operation of the library. The IPCLoadFuncs and IPCDropFuncs register and deregister all the external routines. It is possible to be more specific by using the PipeLoadFuncs, SemLoadFuncs and PipeDropFuncs, SemLoadFuncs procedures. The IPCVersion function returns a version identification string. The IPCContext functions are used to support threads and asynchronous services (ProcCreateThread and PipeConnectAsync). ΓòÉΓòÉΓòÉ 3.1. IPCContextClose function ΓòÉΓòÉΓòÉ Syntax rc = IPCContextClose(ctxHandle) Description IPCContextClose is used to free the memory resources consumed by the IPC Context structure. Arguments ctxHandle as obtained from IPCCreateContext. Returns IPCContextClose returns 0. Notes If a thread is still associated with the context when IPCContextClose is called, that thread is killed. See also IPCContextCreate Examples To close an IPC Context: call IPCContextClose myContext if result \= 0 then signal ContextCloseError ΓòÉΓòÉΓòÉ 3.2. IPCContextCreate function ΓòÉΓòÉΓòÉ Syntax rc = IPCContextCreate(handleVar, [ semHandle ]) Description IPCContextCreate is used to create a context for the execution of an asynchronous (multi-threaded) function. This context holds the completion status and may hold an event semaphore handle to signal the completion of the requested function. It will also hold the result string returned by a thread started with ProcCreateThread. Arguments handleVar is the name of the variable which is to receive the handle to the allocated context. semHandle is the handle of the event semaphore which will be used to signal the completion of the asynchronous function. If this semaphore is not supplied, the function IPCContextWait may be used to wait for completion. Returns IPCContextCreate returns 0. Notes An IPCContext is a structure local to the RexxIPC library. It consumes a few bytes and an internal event semaphore in the current process. The memory and the semaphore is released by a call to IPCContextClose. The internal event semaphore is used for thread synchronization and is not related to the optional semaphore supplied as an argument to this function. See also IPCContextClose, SemEventCreate, PipeConnectAsync, ProcCreateThread Examples To create an IPC Context: call SemEventCreate 'myContextEvent' if result \= 0 then signal SemCreateError call IPCContextCreate 'myContext', myContextEvent if result \= 0 then signal ContextCreateError . . . call IPCContextClose myContext if result \= 0 then signal ContextCloseError call SemEventClose myContextEvent if result \= 0 then signal SemCloseError ΓòÉΓòÉΓòÉ 3.3. IPCContextQuery function ΓòÉΓòÉΓòÉ Syntax rc = IPCContextQuery(ctxHandle, [ threadVar ]) Description IPCContextQuery is used to get the completion code of the last thread associated with the context. If the thread is still active, the system Id may be returned in an optional parameter. Arguments ctxHandle as obtained from IPCCreateContext. threadVar is the name of the variable which is to receive the system Id of the thread active on the context. If there is no such thread, the value will be 0 (zero). Returns IPCContextQuery returns the completion code. Notes If a thread is still active on the context, IPCContextQuery will return the code ERROR_BUSY (170). It will also put a non-zero value in the optional variable parameter. See also IPCContextCreate, IPCContextWait Examples To query an IPC Context used in a PipeConnectAsync: call IPCContextQuery myContext if result \= 0 then signal PipeConnectError ΓòÉΓòÉΓòÉ 3.4. IPCContextResult function ΓòÉΓòÉΓòÉ Syntax threadResult = IPCContextResult(ctxHandle) Description IPCContextResult is used to get the string returned by the thread associated with the context. Arguments ctxHandle as obtained from IPCCreateContext. Returns IPCContextResult returns the string produced by the last Rexx thread associated with the context. It will return a null string if the thread is still active or did not return a string. See also IPCContextCreate, IPCContextQuery, IPCContextWait, ProcCreateThread Examples To get the result from the last thread started by ProcCreateThread: call IPCContextResult myContext say 'The thread returned: "'result'".' ΓòÉΓòÉΓòÉ 3.5. IPCContextWait function ΓòÉΓòÉΓòÉ Syntax rc = IPCContextWait(ctxHandle) Description IPCContextWait is used to wait for the thread associated with the context and get the completion code. If the thread has already completed execution at the time of the call, there will be no wait but the completion code will be returned. Arguments ctxHandle as obtained from IPCCreateContext. Returns IPCContextWait returns the completion code. Notes After IPCContextWait returns, IPCContextResult may be called to get the string (if any) returned by the thread. See also IPCContextCreate, IPCContextQuery, IPCContextResult, ProcCreateThread Examples To wait for an IPC Context used in a PipeConnectAsync: call IPCContextWait myContext if result \= 0 then signal PipeConnectError ΓòÉΓòÉΓòÉ 3.6. IPCDropFuncs procedure ΓòÉΓòÉΓòÉ Syntax call IPCDropFuncs Description IPCDropFuncs deregisters all the library procedures and functions. Arguments No arguments are required by IPCDropFuncs. Returns Nothing is returned by IPCDropFuncs. Notes IPC procedures and functions may be deregistered individually. IPCDropFuncs is only a shortcut to have them all deregistered with one call. See also IPCLoadFuncs, PipeLoadFuncs, PipeDropFuncs, ProcLoadFuncs, ProcDropFuncs, SemLoadFuncs, SemDropFuncs ΓòÉΓòÉΓòÉ 3.7. IPCLoadFuncs procedure ΓòÉΓòÉΓòÉ Syntax call IPCLoadFuncs Description IPCLoadFuncs registers all the library procedures and functions. Arguments No arguments are required by IPCLoadFuncs. Returns Nothing is returned by IPCLoadFuncs. Notes IPC procedures and functions must be registered before they can be used. They may be registered individually. IPCLoadFuncs is only a shortcut to have them all registered with one call. See also IPCDropFuncs, PipeLoadFuncs, PipeDropFuncs, ProcLoadFuncs, ProcDropFuncs, SemLoadFuncs, SemDropFuncs Examples To register all the RexxIPC functions: call RxFuncAdd 'IPCLoadFuncs', 'REXXIPC', 'IPCLoadFuncs' call IPCLoadFuncs ΓòÉΓòÉΓòÉ 3.8. IPCVersion function ΓòÉΓòÉΓòÉ Syntax versionString = IPCVersion() Description IPCVersion may be used to identify the version of the IPC library. Arguments No arguments are required by IPCVersion. Returns IPCVersion currently returns a string with the format producer product major.minor-revision but this may change in the future. ΓòÉΓòÉΓòÉ 4. Pipe Procedures and Functions ΓòÉΓòÉΓòÉ The Pipe prefix identifies named pipe related functions. Some of these are not pipe specific in the operating system implementation (like DosRead used by PipeRead, or DosClose used by PipeClose), but are needed for pipe operations. Some functions are most often used by the server side of an application (like PipeCreate, PipeConnect and PipeDisconnect), while others are used by the client side (like PipeOpen, PipeWait, PipeCall and PipeTransact). The "Control Program Guide and Reference" (Developer's Toolkit for OS/2) or "Client/Server Programming with OS/2 2.0" (Van Nostrand Reinhold) are valuable sources of information. Note: The pipe handle mentionned in the individual Pipe functions description is the actual value used by the operating system, converted to an unsigned decimal number character string. It is not associated with internal structures of the RexxIPC library and may be created/used by other modules of the same process. ΓòÉΓòÉΓòÉ 4.1. PipeCall function ΓòÉΓòÉΓòÉ Syntax rc = PipeCall(name, output, inputVar, [ inputLimit ], [ timeout ]) Description PipeCall executes a call operation. It combines the effect of PipeOpen, PipeTransact and PipeClose. Arguments name specifies the name for the pipe. It must have the form: [\\serverName ]\PIPE\pipeName where: serverName is the name of the server on which the pipe has been created; pipeName is the actual name of the pipe. output is the string expression to be sent on the pipe. inputVar is the name of the variable which is to receive the response. inputLimit is the size limit (in bytes) for the response. If zero or omitted, a default of 4096 is used. timeout is the wait timeout in milliseconds. The default is 50. This timeout refers to the time the directive will wait for a pipe instance to become available. Returns PipeCall returns the code supplied by the DosCallNPipe system directive. Notes The named pipe must have been created in duplex mode with message format. See also PipeOpen, PipeWait, PipeTransact, PipeClose Examples To make a call on a named pipe: call PipeCall '\PIPE\MY_SERVER_PIPE', 'Hello?', 'answer' if result \= 0 then signal PipeCallError say 'Pipe answer: "'answer'".' ΓòÉΓòÉΓòÉ 4.2. PipeClose function ΓòÉΓòÉΓòÉ Syntax rc = PipeClose(pipeHandle) Description PipeClose closes a pipe. It is called both for a created pipe (server side), and for an opened pipe (client side). Arguments pipeHandle as obtained from PipeCreate or PipeOpen. Returns PipeClose returns the code supplied by the DosClose system directive. See also PipeCreate, PipeOpen Examples To close a named pipe: call PipeClose pipe if result \= 0 then signal PipeCloseError ΓòÉΓòÉΓòÉ 4.3. PipeConnect function ΓòÉΓòÉΓòÉ Syntax rc = PipeConnect(pipeHandle) Description PipeConnect listens for a connection on a named pipe. Arguments pipeHandle as obtained from PipeCreate. Returns PipeConnect returns the code supplied by the DosConnectNPipe system directive. See also PipeCreate, PipeConnectAsync, PipeOpen, PipeDisconnect Examples To create a named pipe and listen for a connection: call PipeCreate 'pipe', '\PIPE\MY_PIPE' if result \= 0 then signal PipeCreateError call PipeConnect pipe if result \= 0 then signal PipeConnectError To answer requests from PipeCall or PipeTransact calls: call PipeCreate 'pipe', '\PIPE\MY_PIPE' if result \= 0 then signal PipeCreateError do forever call PipeConnect pipe if result \= 0 then signal PipeConnectError do forever call PipeRead pipe, 'request' if result \= 0 then signal PipeReadError if request = '' then leave . . . call PipeWrite pipe, 'answer' if result \= 0 then signal PipeWriteError end call PipeDisconnect pipe if result \= 0 then signal PipeDisconnectError end ΓòÉΓòÉΓòÉ 4.4. PipeConnectAsync function ΓòÉΓòÉΓòÉ Syntax rc = PipeConnectAsync(pipeHandle, ctxHandle) Description PipeConnectAsync listens for a connection on a named pipe. Arguments pipeHandle as obtained from PipeCreate. ctxHandle as obtained from IPCContextCreate. Returns PipeConnectAsync returns the code supplied by the DosCreateThread system directive. See also IPCContextCreate, PipeConnect, SemEventWait Examples To create a pipe and start a process which will immediately open the pipe: call PipeCreate 'pipe', '\PIPE\REDIRECTED_INPUT' if result \= 0 then signal PipeCreateError call IPCContextCreate 'context' if result \= 0 then signal ContextCreateError call PipeConnectAsync pipe, context if result \= 0 then signal PipeConnectAsyncError 'DETACH RED_PROC <\PIPE\REDIRECTED_INPUT >NUL' call IPCContextWait context if result \= 0 then signal PipeConnectError ΓòÉΓòÉΓòÉ 4.5. PipeCreate function ΓòÉΓòÉΓòÉ Syntax rc = PipeCreate(handleVar, name, [ mode ], [ format ], [ instances ], [ outBufSize ], [ inpBufSize ], [ timeout ]) Description PipeCreate is used to create a named pipe. Arguments handleVar is the name of a variable which is to receive the handle to the named pipe. name specifies the name for the pipe. It must have the form: \PIPE\pipeName where: pipeName is the actual name of the pipe. mode is the pipe access mode. If present, it must be one of the following keywords: Inbound for an inbound pipe (receive only); Outbound for an outbound pipe (transmit only); Duplex for a duplex pipe (transmit and receive), this is the default. The keywords are case insensitive and may be abbreviated. format is the pipe format. If present, it must be one of the following keywords: Byte for a byte pipe (no implicit length); Message for a message pipe (implicit length), this is the default. The keywords are case insensitive and may be abbreviated. instances is the maximum number of instances for this pipe. It must be a value between 1 and 255, or -1 (meaning no limit). The default is 1. outBufSize is the output buffer size. The default is 1024. inpBufSize is the input buffer size. The default is 1024. timeout is the default wait timeout in milliseconds. The default is 50. Returns PipeCreate returns the code supplied by the DosCreateNPipe system directive. Notes If the return code is non-zero, handleVar is not created or modified. See also PipeOpen, PipeClose Examples To create a named pipe: call PipeCreate 'pipe', '\PIPE\MY_PIPE' if result \= 0 then signal PipeCreateError ΓòÉΓòÉΓòÉ 4.6. PipeDisconnect function ΓòÉΓòÉΓòÉ Syntax rc = PipeDisconnect(pipeHandle) Description PipeDisconnect drops a connection on a named pipe. Arguments pipeHandle as obtained from PipeCreate. Returns PipeDisconnect returns the code supplied by the DosDisConnectNPipe system directive. See also PipeCreate, PipeConnect ΓòÉΓòÉΓòÉ 4.7. PipeDropFuncs procedure ΓòÉΓòÉΓòÉ Syntax call PipeDropFuncs Description PipeDropFuncs deregisters all the Pipe procedures and functions. Arguments No arguments are required by PipeDropFuncs. Returns Nothing is returned by PipeDropFuncs. Notes Pipe procedures and functions may be deregistered individually. PipeDropFuncs is only a shortcut to have them all deregistered with one call. IPCDropFuncs will by itself call PipeDropFuncs and deregister it. See also IPCDropFuncs, PipeLoadFuncs ΓòÉΓòÉΓòÉ 4.8. PipeFlush function ΓòÉΓòÉΓòÉ Syntax rc = PipeFlush(pipeHandle) Description PipeFlush flushes the write buffer of a named pipe. It may be called both for a created pipe (server side), and for an opened pipe (client side). Arguments pipeHandle as obtained from PipeCreate or PipeOpen. Returns PipeFlush returns the code supplied by the DosFlush system directive. See also PipeClose Examples To flush a named pipe: call PipeFlush pipe if result \= 0 then signal PipeFlushError ΓòÉΓòÉΓòÉ 4.9. PipeLoadFuncs procedure ΓòÉΓòÉΓòÉ Syntax call PipeLoadFuncs Description PipeLoadFuncs registers all the Pipe procedures and functions. Arguments No arguments are required by PipeLoadFuncs. Returns Nothing is returned by PipeLoadFuncs. Notes Pipe procedures and functions must be registered before they can be used. They may be registered individually. PipeLoadFuncs is only a shortcut to have them all registered with one call. IPCLoadFuncs will by itself register and call PipeLoadFuncs. See also IPCLoadFuncs, PipeDropFuncs ΓòÉΓòÉΓòÉ 4.10. PipeOpen function ΓòÉΓòÉΓòÉ Syntax rc = PipeOpen(handleVar, name, [ mode ], [ format ]) Description PipeOpen is used to open a named pipe. Arguments handleVar is the name of a variable which is to receive the handle to the named pipe. name specifies the name for the pipe. It must have the form: [\\serverName ]\PIPE\pipeName where: serverName is the name of the server on which the pipe has been created; pipeName is the actual name of the pipe. mode is the pipe access mode. If present, it must be one of the following keywords: Inbound for an inbound pipe (receive only); Outbound for an outbound pipe (transmit only); Duplex for a duplex pipe (transmit and receive), this is the default. The keywords are case insensitive and may be abbreviated. format is the pipe format. If present, it must be one of the following keywords: Byte for a byte pipe (no implicit length); Message for a message pipe (implicit length), this is the default. The keywords are case insensitive and may be abbreviated. Returns PipeOpen returns the code supplied by the DosOpen system directive. Notes If the return code is non-zero, handleVar is not created or modified. See also PipeCreate, PipeClose Examples To open a named pipe: call PipeOpen 'pipe', '\PIPE\MY_SERVER_PIPE' if result \= 0 then signal PipeOpenError ΓòÉΓòÉΓòÉ 4.11. PipePeek function ΓòÉΓòÉΓòÉ Syntax rc = PipePeek(pipeHandle, [ inputVar ], [ inputLimit ], [ pipeBytesVar ], [ msgBytesVar ], [ stateVar ]) Description PipePeek performs a read operation on a named pipe. The operation returns immediatly with the currently available data as well as with other requested informations. Arguments pipeHandle as obtained from PipeCreate or PipeOpen. inputVar is the name of the variable which is to receive the data. inputLimit is the allowed size limit for the response. If zero or omitted, a default limit of 4096 is used. pipeBytesVar is the name of the variable which is to receive the number of bytes held in the pipe buffer. msgBytesVar is the name of the variable which is to receive the number of bytes held in the pipe buffer for the current message. stateVar is the name of the variable which is to receive a code identifying the state of the pipe: 1: the pipe is disconnected; 2: the pipe is listening for a connection; 3: the pipe is connected; 4: the pipe is closing. Returns PipePeek returns the code supplied by the DosPeekNPipe system directive. See also PipeRead Examples To peek for a maximum of 80 bytes from a named pipe: call PipePeek pipe, 'data', 80, 'pipeBytes', 'msgBytes', 'state' if result \= 0 then signal PipePeekError say 'Pipe data:' data say 'Pipe bytes held:' pipeBytes say 'Pipe bytes in message:' msgBytes say 'Pipe state:' state ΓòÉΓòÉΓòÉ 4.12. PipeRead function ΓòÉΓòÉΓòÉ Syntax rc = PipeRead(pipeHandle, inputVar, [ inputLimit ]) Description PipeRead performs a blocking read operation on a named pipe. Arguments pipeHandle as obtained from PipeCreate or PipeOpen. inputVar is the name of the variable which is to receive the data. inputLimit is the allowed size limit for the response. If zero or omitted, a default limit of 4096 is used. Returns PipeRead returns the code supplied by the DosRead system directive. See also PipeWrite, PipePeek Examples To read from a named pipe: call PipeRead pipe, 'data' if result \= 0 then signal PipeReadError say 'Pipe data:' data ΓòÉΓòÉΓòÉ 4.13. PipeSetSem function ΓòÉΓòÉΓòÉ Syntax rc = PipeSetSem(pipeHandle, semHandle) Description PipeSetSem associates a shared event semaphore with the pipe. Read and write operations on the other end of the pipe will post events on that semaphore. Arguments pipeHandle as obtained from PipeCreate or PipeOpen. semHandle as obtained from SemEventCreate or SemEventOpen Returns PipeSetSem returns the code supplied by the DosSetNPipeSem system directive. See also SemEventCreate, SemEventWait, PipeRead, PipeWrite Examples To associate a shared event semaphore to a pipe: call SemEventCreate 'event', 'Shared' if result \= 0 then signal SemCreateError call PipeSetSem pipe, event if result \= 0 then signal PipeSetSemError . . . call SemEventWait event if result \= 0 then signal SemWaitError ΓòÉΓòÉΓòÉ 4.14. PipeTransact function ΓòÉΓòÉΓòÉ Syntax rc = PipeTransact(pipeHandle, output, inputVar, [ inputLimit ]) Description PipeTransact combines the effect of PipeWrite and PipeRead. Arguments pipeHandle as obtained from PipeCreate or PipeOpen. output is the string expression to be sent on the pipe. inputVar is the name of the variable which is to receive the response. inputLimit is the allowed size limit for the response. If zero or omitted, a default limit of 4096 is used. Returns PipeTransact returns the code supplied by the DosTransactNPipe system directive. Notes The pipe must have been created in duplex mode with message format. See also PipeCall, PipeRead, PipeWrite Examples To make a named pipe transaction: call PipeTransact pipe, 'Hello?', 'answer' if result \= 0 then signal PipeTransactError say 'Pipe answer:' answer ΓòÉΓòÉΓòÉ 4.15. PipeWait function ΓòÉΓòÉΓòÉ Syntax rc = PipeWait(name, [ timeout ]) Description PipeWait performs a wait on a busy named pipe. Arguments name specifies the name for the pipe. It must have the form: [\\serverName ]\PIPE\pipeName where: serverName is the name of the server on which the pipe has been created; pipeName is the actual name of the pipe. timeout is the wait timeout in milliseconds. A value of -1 means an infinite wait; 0 or no value uses the value specified in the PipeCreate call. Returns PipeWait returns the code supplied by the DosWaitNPipe system directive. See also PipeOpen Examples To open a very busy named pipe: do forever call PipeOpen 'pipe', '\PIPE\MY_SERVER_PIPE' if result = 0 then leave if result \= 231 then signal PipeOpenError call PipeWait '\PIPE\MY_SERVER_PIPE', -1 if result \= 0 then signal PipeWaitError end ΓòÉΓòÉΓòÉ 4.16. PipeWrite function ΓòÉΓòÉΓòÉ Syntax rc = PipeWrite(pipeHandle, output) Description PipeWrite performs a blocking write operation on a named pipe. Arguments pipeHandle as obtained from PipeCreate or PipeOpen. output is the string expression to be sent on the pipe. Returns PipeWrite returns the code supplied by the DosWrite system directive. See also PipeRead Examples To write on a named pipe: call PipeWrite pipe, 'Hello, Pipe!' if result \= 0 then signal PipeWriteError ΓòÉΓòÉΓòÉ 5. Process Procedures and Functions ΓòÉΓòÉΓòÉ The Proc prefix identifies process related functions. The "Control Program Guide and Reference" (Developer's Toolkit for OS/2) or "Client/Server Programming with OS/2 2.0" (Van Nostrand Reinhold) are valuable sources of information. Note: The facilities provided by these functions are simple mapping to the corresponding system services. They should by used with caution, since they are much more likely to affect other processes in the system than the other function groups in this library. ΓòÉΓòÉΓòÉ 5.1. ProcCreateThread function ΓòÉΓòÉΓòÉ Syntax rc = ProcCreateThread([ ctxHandle ], commandFile, [ ... ]) Description ProcCreateThread is used to create and start a Rexx thread. Arguments ctxHandle as obtained from IPCContextCreate. This context is used to anchor the execution of the thread. If this parameter is not supplied, a temporary context will be automatically generated before the thread is started and discarded after the thread has terminated. commandFile is the name of a Rexx command file to be executed by the Rexx interpreter in the thread. ... these parameters will be passed to the Rexx program. Returns ProcSendSignal returns the code supplied by the DosCreateThread system directive. Notes The use of an explicit context allows for a more controlled execution of the started thread. It is then possible to specify an event semaphore to IPCContextCreate which will be posted when the thread terminates, to periodically check the thread with IPCContextQuery, to wait for the thread to terminate and get the return code with IPCContextWait, to get the result string returned by the thread with IPCContextResult, and to terminate the thread with IPCContextClose. Thread synchronization and resource access control may be done with Semaphore functions. The Rexx Queue facility (RxQueue and LineIn functions; Push, Pull and Queue keywords) may be used to support communication between threads. Examples To start and forget a thread: call ProcCreateThread , 'thread.cmd' if result \= 0 then signal CreateThreadError To start a thread, do some processing, then wait and get the thread result: call IPCContextCreate 'context' if result \= 0 then signal CreateContextError call ProcCreateThread context, 'thread.cmd', '1st', '2nd' if result \= 0 then signal CreateThreadError . . . call IPCContextWait context if result \= 0 then signal ThreadTerminatedOnError call IPCContextResult context say 'The thread returned: "'result'".' ΓòÉΓòÉΓòÉ 5.2. ProcDropFuncs procedure ΓòÉΓòÉΓòÉ Syntax call ProcDropFuncs Description ProcDropFuncs deregisters all the process procedures and functions. Arguments No arguments are required by ProcDropFuncs. Returns Nothing is returned by ProcDropFuncs. Notes Process procedures and functions may be deregistered individually. ProcDropFuncs is only a shortcut to have them all deregistered with one call. IPCDropFuncs will by itself call ProcDropFuncs and deregister it. See also IPCDropFuncs, ProcLoadFuncs ΓòÉΓòÉΓòÉ 5.3. ProcLoadFuncs procedure ΓòÉΓòÉΓòÉ Syntax call ProcLoadFuncs Description ProcLoadFuncs registers all the process procedures and functions. Arguments No arguments are required by ProcLoadFuncs. Returns Nothing is returned by ProcLoadFuncs. Notes Process procedures and functions must be registered before they can be used. They may be registered individually. ProcLoadFuncs is only a shortcut to have them all registered with one call. IPCLoadFuncs will by itself register and call ProcLoadFuncs. See also IPCLoadFuncs, ProcDropFuncs ΓòÉΓòÉΓòÉ 5.4. ProcSendSignal function ΓòÉΓòÉΓòÉ Syntax rc = ProcSendSignal(processId, signal) Description ProcSendSignal is used to send a signal (Break, Interrupt or Kill) to a process. Arguments processId is the process identification for the target process. signal identifies the signal to send. It must be one of the following keywords: Break send a Break (Ctrl+Break) signal; Interrupt send an Interrupt (Ctrl+C) signal; Kill send a Kill signal. The keywords are case insensitive and may be abbreviated. Returns ProcSendSignal returns the code supplied by the DosSendSignalException or DosKillProcess system directive. Examples To kill a process: call ProcSendSignal processId, 'Kill' if result \= 0 then signal ProcessKillError ΓòÉΓòÉΓòÉ 5.5. ProcSetPriority function ΓòÉΓòÉΓòÉ Syntax rc = ProcSetPriority([ processId ], [ class ], [ delta ]) Description ProcSetPriority is used to modify the execution priority of a process. Arguments processId is the system identification for the target process. Absence or 0 (zero) identifies the calling process. class is the new priority class. If present, it must be one of the following keywords: Idle identifies the Idle (lowest) priority class; Regular identifies the Regular (default) priority class; Server identifies the Server (high) priority class; Critical identifies the Critical (highest) priority class. The keywords are case insensitive and may be abbreviated. delta if the class is not specified, this is the priority variation within the current class and may range from -31 to +31; if the class is specified, this is the absolute priority within that class and may range from 0 to +31. Returns ProcSetPriority returns the code supplied by the DosSetPriority system directive. See also ProcSetThreadPriority, ProcSetTreePriority Examples To set the priority of the current process to 20 in the Idle class: call ProcSetPriority 0, 'Idle', 20 if result \= 0 then signal SetPriorityError ΓòÉΓòÉΓòÉ 5.6. ProcSetThreadPriority function ΓòÉΓòÉΓòÉ Syntax rc = ProcSetThreadPriority([ threadId ], [ class ], [ delta ]) Description ProcSetThreadPriority is used to modify the execution priority of a thread. Arguments threadId is the system identification for the target thread. Absence or 0 (zero) identifies the calling thread. class is the new priority class. If present, it must be one of the following keywords: Idle identifies the Idle (lowest) priority class; Regular identifies the Regular (default) priority class; Server identifies the Server (high) priority class; Critical identifies the Critical (highest) priority class. The keywords are case insensitive and may be abbreviated. delta if the class is not specified, this is the priority variation within the current class and may range from -31 to +31; if the class is specified, this is the absolute priority within that class and may range from 0 to +31. Returns ProcSetThreadPriority returns the code supplied by the DosSetPriority system directive. See also ProcSetPriority, ProcSetTreePriority Examples To set the priority of the current thread to 20 in the Idle class: call ProcSetThreadPriority 0, 'Idle', 20 if result \= 0 then signal SetPriorityError ΓòÉΓòÉΓòÉ 5.7. ProcSetTreePriority function ΓòÉΓòÉΓòÉ Syntax rc = ProcSetTreePriority([ processId ], [ class ], [ delta ]) Description ProcSetPriority is used to modify the execution priority of a process tree. Arguments processId is the system identification for the parent process of the target process tree. Absence or 0 (zero) identifies the calling process as the parent. class is the new priority class. If present, it must be one of the following keywords: Idle identifies the Idle (lowest) priority class; Regular identifies the Regular (default) priority class; Server identifies the Server (high) priority class; Critical identifies the Critical (highest) priority class. The keywords are case insensitive and may be abbreviated. delta if the class is not specified, this is the priority variation within the current class and may range from -31 to +31; if the class is specified, this is the absolute priority within that class and may range from 0 to +31. Returns ProcSetPriority returns the code supplied by the DosSetPriority system directive. See also ProcSetPriority, ProcSetThreadPriority Examples To set the priority of the current process tree to 20 in the Idle class: call ProcSetTreePriority 0, 'Idle', 20 if result \= 0 then signal SetPriorityError ΓòÉΓòÉΓòÉ 6. Semaphore Procedures and Functions ΓòÉΓòÉΓòÉ The Sem prefix identifies semaphore related function. Except for a few procedures (SemLoadFuncs and SemDropFuncs), the prefix is expressed as SemEvent, SemMutex or SemMuxwait, to specify to which type of semaphore the function applies. The "Control Program Guide and Reference" (Developer's Toolkit for OS/2) or "Client/Server Programming with OS/2 2.0" (Van Nostrand Reinhold) are valuable sources of information. Note: The semaphore handle mentionned in the individual semaphore functions description is the actual value used by the operating system, converted to an unsigned decimal number character string. It is not associated with internal structures of the RexxIPC library and may be created/used by other modules of the same process. ΓòÉΓòÉΓòÉ 6.1. SemDropFuncs procedure ΓòÉΓòÉΓòÉ Syntax call SemDropFuncs Description SemDropFuncs deregisters all the semaphore procedures and functions. Arguments No arguments are required by SemDropFuncs. Returns Nothing is returned by SemDropFuncs. Notes Semaphore procedures and functions may be deregistered individually. SemDropFuncs is only a shortcut to have them all deregistered with one call. IPCDropFuncs will by itself call SemDropFuncs and deregister it. See also IPCLoadFuncs, IPCDropFuncs, SemLoadFuncs ΓòÉΓòÉΓòÉ 6.2. SemEventClose function ΓòÉΓòÉΓòÉ Syntax rc = SemEventClose(semHandle) Description SemEventClose closes an event semaphore. Arguments semHandle as obtained from SemEventCreate or SemEventOpen. Returns SemEventClose returns the code supplied by the DosCloseEventSem system directive. See also SemEventCreate, SemEventOpen Examples To close an event semaphore: call SemEventClose sem if result \= 0 then signal SemCloseError ΓòÉΓòÉΓòÉ 6.3. SemEventCreate function ΓòÉΓòÉΓòÉ Syntax rc = SemEventCreate(handleVar, [ name ], [ initial ]) Description SemEventCreate is used to create an event semaphore. Arguments handleVar is the name of a variable which is to receive the handle to the event semaphore. name specifies the name for the semaphore. If present, it must have the form: \SEM32\semName where: semName is the name of the semaphore. If a name is not specified, the keyword Shared (case insensitive and may be abbreviated) can be used to create a shared unnamed semaphore; otherwise a local semaphore is created. initial is the initial state of the event semaphore: posted (1) or reset (0). The default is 0. Returns SemEventCreate returns the code supplied by the DosCreateEventSem system directive. Notes If the return code is non-zero, handleVar is not created or modified. See also SemEventOpen, SemEventClose Examples To create an event semaphore or just open if it already exists: semName = '\SEM32\MY_SEMAPHORE' call SemEventCreate 'sem', semName if result = 285 then call SemEventOpen 'sem', semName if result \= 0 then signal SemCreateError ΓòÉΓòÉΓòÉ 6.4. SemEventOpen function ΓòÉΓòÉΓòÉ Syntax rc = SemEventOpen(handleVar, name) Description SemEventOpen is used to open a named event semaphore. Arguments handleVar is the name of a variable which is to receive the handle to the event semaphore. name specifies the name for the semaphore. It must have the form: \SEM32\semName where: semName is the name of the semaphore. Returns SemEventOpen returns the code supplied by the DosOpenEventSem system directive. Notes If the return code is non-zero, handleVar is not created or modified. See also SemEventCreate, SemEventClose Examples To open a named event semaphore: call SemEventOpen 'sem', '\SEM32\A_NAMED_SEMAPHORE' if result \= 0 then signal SemOpenError ΓòÉΓòÉΓòÉ 6.5. SemEventPost function ΓòÉΓòÉΓòÉ Syntax rc = SemEventPost(semHandle) Description SemEventPost posts an event semaphore. Arguments semHandle as obtained from SemEventCreate or SemEventOpen. Returns SemEventPost returns the code supplied by the DosPostEventSem system directive. See also SemEventReset, SemEventQuery, SemEventWait Examples To post an event: call SemEventPost sem if result \= 0 then signal SemPostError ΓòÉΓòÉΓòÉ 6.6. SemEventQuery function ΓòÉΓòÉΓòÉ Syntax rc = SemEventQuery(semHandle, postCountVar) Description SemEventQuery queries informations from an event semaphore. Arguments semHandle as obtained from SemEventCreate or SemEventOpen postCountVar is the name of the variable which is to hold the number of post actions since the last time the semaphore was in a reset state. Returns SemEventQuery returns the code supplied by the DosQueryEventSem system directive. See also SemEventReset, SemEventPost, SemEventWait Examples To query an event semaphore: call SemEventQuery sem, 'count' if result \= 0 then signal SemQueryError say 'Semaphore post count:' count ΓòÉΓòÉΓòÉ 6.7. SemEventReset function ΓòÉΓòÉΓòÉ Syntax rc = SemEventReset(semHandle, [ postCountVar ]) Description SemEventReset resets an event semaphore. Arguments semHandle as obtained from SemEventCreate or SemEventOpen. postCountVar if present, is the name of the variable which is to hold the number of post actions since the last time the semaphore was in a reset state. Returns SemEventReset returns the code supplied by the DosResetEventSem system directive. See also SemEventPost, SemEventQuery, SemEventWait Examples To reset an event semaphore: call SemEventReset sem if result \= 0 then signal SemResetError ΓòÉΓòÉΓòÉ 6.8. SemEventWait function ΓòÉΓòÉΓòÉ Syntax rc = SemEventWait(semHandle, [ timeout ]) Description SemEventWait waits for an event semaphore to be in a non reset state. Arguments semHandle as obtained from SemEventCreate or SemEventOpen. timeout is the wait timeout in milliseconds. A value of -1 means an infinite wait; this is the default. Returns SemEventWait returns the code supplied by the DosWaitEventSem system directive. See also SemEventPost, SemEventReset, SemEventQuery Examples To wait for an event semaphore: call SemEventWait sem if result \= 0 then signal SemWaitError ΓòÉΓòÉΓòÉ 6.9. SemLoadFuncs procedure ΓòÉΓòÉΓòÉ Syntax call SemLoadFuncs Description SemLoadFuncs registers all the semaphore procedures and functions. Arguments No arguments are required by SemLoadFuncs. Returns Nothing is returned by SemLoadFuncs. Notes Semaphore procedures and functions must be registered before they can be used. They may be registered individually. SemLoadFuncs is only a shortcut to have them all registered with one call. IPCLoadFuncs will by itself register and call SemLoadFuncs. See also IPCLoadFuncs, SemDropFuncs ΓòÉΓòÉΓòÉ 6.10. SemMutexClose function ΓòÉΓòÉΓòÉ Syntax rc = SemMutexClose(semHandle) Description SemMutexClose closes a mutex semaphore. Arguments semHandle as obtained from SemMutexCreate or SemMutexOpen. Returns SemMutexClose returns the code supplied by the DosCloseMutexSem system directive. See also SemMutexCreate, SemMutexOpen Examples To close a mutex semaphore: call SemMutexClose sem if result \= 0 then signal SemCloseError ΓòÉΓòÉΓòÉ 6.11. SemMutexCreate function ΓòÉΓòÉΓòÉ Syntax rc = SemMutexCreate(handleVar, [ name ], [ initial ]) Description SemMutexCreate is used to create a mutex semaphore. Arguments handleVar is the name of a variable which is to receive the handle to the mutex semaphore. name specifies the name for the semaphore. If present, it must have the form: \SEM32\semName where: semName is the name of the semaphore. If a name is not specified, the keyword Shared (case insensitive and may be abbreviated) can be used to create a shared unnamed semaphore; otherwise a local semaphore is created. initial is the initial state of the mutex semaphore: held (1) or released (0). The default is 0. Returns SemMutexCreate returns the code supplied by the DosCreateMutexSem system directive. Notes If the return code is non-zero, handleVar is not created or modified. See also SemMutexOpen, SemMutexClose Examples To create a mutex semaphore: call SemMutexCreate 'sem', '\SEM32\MY_SEMAPHORE' if result \= 0 then signal SemCreateError ΓòÉΓòÉΓòÉ 6.12. SemMutexOpen function ΓòÉΓòÉΓòÉ Syntax rc = SemMutexOpen(handleVar, name) Description SemMutexOpen is used to open a named mutex semaphore. Arguments handleVar is the name of a variable which is to receive the handle to the mutex semaphore. name specifies the name for the semaphore. It must have the form: \SEM32\semName where: semName is the name of the semaphore. Returns SemMutexOpen returns the code supplied by the DosOpenMutexSem system directive. Notes If the return code is non-zero, handleVar is not created or modified. See also SemMutexCreate, SemMutexClose Examples To open a named mutex semaphore: call SemMutexOpen 'sem', '\SEM32\A_NAMED_SEMAPHORE' if result \= 0 then signal SemOpenError ΓòÉΓòÉΓòÉ 6.13. SemMutexQuery function ΓòÉΓòÉΓòÉ Syntax rc = SemMutexQuery(semHandle, [ processIdVar ], [ threadIdVar ], [ countVar ]) Description SemMutexQuery queries informations from a mutex semaphore. Arguments semHandle as obtained from SemMutexCreate or SemMutexOpen. processIdVar if present, is the name of the variable which is to hold the id of the owner process. threadIdVar if present, is the name of the variable which is to hold the id of the owner thread. countVar if present, is the name of the variable which is to hold the request count from the owner process. If the semaphore is unowned, the count is zero. Returns SemMutexQuery returns the code supplied by the DosQueryMutexSem system directive. See also SemMutexRequest, SemMutexRelease Examples To query a mutex semaphore: call SemMutexQuery sem, 'processId', 'threadId', 'count' if result \= 0 then signal SemQueryError say 'Semaphore post count:' count if count \= 0 then do say 'Semaphore owner process:' processId say 'Semaphore owner thread:' threadId end ΓòÉΓòÉΓòÉ 6.14. SemMutexRelease function ΓòÉΓòÉΓòÉ Syntax rc = SemMutexRelease(semHandle) Description SemMutexRelease releases a mutex semaphore. Arguments semHandle as obtained from SemMutexCreate or SemMutexOpen. Returns SemMutexRelease returns the code supplied by the DosReleaseMutexSem system directive. See also SemMutexRequest, SemMutexQuery Examples To release a mutex semaphore: call SemMutexRelease sem if result \= 0 then signal SemReleaseError ΓòÉΓòÉΓòÉ 6.15. SemMutexRequest function ΓòÉΓòÉΓòÉ Syntax rc = SemMutexRequest(semHandle, [ timeout ]) Description SemMutexRequest requests to be the owner of a mutex semaphore. Arguments semHandle as obtained from SemMutexCreate or SemMutexOpen. timeout is the wait timeout in milliseconds. A value of -1 means an infinite wait; this is the default. Returns SemMutexRequest returns the code supplied by the DosRequestMutexSem system directive. See also SemMutexCreate, SemMutexRelease, SemMutexQuery Examples To request a mutex semaphore: call SemMutexRequest sem if result \= 0 then signal SemRequestError ΓòÉΓòÉΓòÉ 6.16. SemMuxwaitAdd function ΓòÉΓòÉΓòÉ Syntax rc = SemMuxwaitAdd(semHandle, otherSemHandle, [ userValue ]) Description SemMuxwaitAdd adds a semaphore to the associated semaphores list. Arguments semHandle as obtained from SemMuxwaitCreate or SemMuxwaitOpen. otherSemHandle as obtained from SemEventCreate, SemEventOpen, SemMutexCreate, or SemMutexOpen. userValue a numeric value to be returned by SemMuxwaitWait. Returns SemMuxwaitAdd returns the code supplied by the DosAddMuxWaitSem system directive. See also SemMuxwaitCreate, SemMuxwaitOpen, SemMuxwaitRemove, SemEventCreate, SemEventOpen, SemMutexCreate, SemMutexOpen Examples To add an event semaphore to a muxwait semaphore: call SemEventCreate 'eventSem' if result \= 0 then signal SemCreateError call SemMuxwaitAdd muxSem, eventSem, 1 if result \= 0 then signal SemAddError ΓòÉΓòÉΓòÉ 6.17. SemMuxwaitClose function ΓòÉΓòÉΓòÉ Syntax rc = SemMuxwaitClose(semHandle) Description SemMuxwaitClose closes a muxwait semaphore. Arguments semHandle as obtained from SemMuxwaitCreate or SemMuxwaitOpen. Returns SemMuxwaitClose returns the code supplied by the DosCloseMuxWaitSem system directive. See also SemMuxwaitCreate, SemMuxwaitOpen Examples To close a muxwait semaphore: call SemMuxwaitClose sem if result \= 0 then signal SemCloseError ΓòÉΓòÉΓòÉ 6.18. SemMuxwaitCreate function ΓòÉΓòÉΓòÉ Syntax rc = SemMuxwaitCreate(handleVar, [ name ], mode) Description SemMuxwaitCreate is used to create a muxwait semaphore. Arguments handleVar is the name of a variable which is to receive the handle to the muxwait semaphore. name specifies the name for the semaphore. If present, it must have the form: \SEM32\semName where: semName is the name of the semaphore. If a name is not specified, the keyword Shared (case insensitive and may be abbreviated) can be used to create a shared unnamed semaphore; otherwise a local semaphore is created. mode is the muxwait semaphore wait mode. It must be one of the following keywords: And wait for all associated semaphores; Or wait for any associated semaphore. The keywords are case insensitive and may be abbreviated. Returns SemMuxwaitCreate returns the code supplied by the DosCreateMuxWaitSem system directive. Notes If the return code is non-zero, handleVar is not created or modified. See also SemMuxwaitAdd, SemMuxwaitOpen, SemMuxwaitClose SemMuxwaitWait, Examples To create a muxwait semaphore: call SemMuxwaitCreate 'sem', '\SEM32\MY_MUXWAIT_SEM', 'Or' if result \= 0 then signal SemCreateError ΓòÉΓòÉΓòÉ 6.19. SemMuxwaitOpen function ΓòÉΓòÉΓòÉ Syntax rc = SemMuxwaitOpen(handleVar, name) Description SemMutexOpen is used to open a named muxwait semaphore. Arguments handleVar is the name of a variable which is to receive the handle to the muxwait semaphore. name specifies the name for the semaphore. It must have the form: \SEM32\semName where: semName is the name of the semaphore. Returns SemMuxwaitOpen returns the code supplied by the DosOpenMuxWaitSem system directive. Notes If the return code is non-zero, handleVar is not created or modified. See also SemMuxwaitCreate, SemMuxwaitClose Examples To open a named muxwait semaphore: call SemMuxwaitOpen 'sem', '\SEM32\A_NAMED_MUXWAIT_SEM' if result \= 0 then signal SemOpenError ΓòÉΓòÉΓòÉ 6.20. SemMuxwaitRemove function ΓòÉΓòÉΓòÉ Syntax rc = SemMuxwaitRemove(semHandle, otherSemHandle) Description SemMuxwaitRemove removes a semaphore from the associated semaphores list. Arguments semHandle as obtained from SemMuxwaitCreate or SemMuxwaitOpen. otherSemHandle as obtained from SemEventCreate, SemEventOpen, SemMutexCreate, or SemMutexOpen. Returns SemMuxwaitRemove returns the code supplied by the DosDeleteMuxWaitSem system directive. See also SemMuxwaitAdd Examples To remove an event semaphore from a muxwait semaphore: call SemMuxwaitRemove muxSem, eventSem if result \= 0 then signal SemRemoveError ΓòÉΓòÉΓòÉ 6.21. SemMuxwaitWait function ΓòÉΓòÉΓòÉ Syntax rc = SemMuxwaitWait(semHandle, [ timeout ], [ userVar ]) Description SemMuxwaitWait waits for a muxwait semaphore. Arguments semHandle as obtained from SemMuxwaitCreate or SemMuxwaitOpen. timeout is the wait timeout in milliseconds. A value of -1 means an infinite wait; this is the default. userVar is the name of a variable which is to receive the optional value specified with the SemMuxwaitAdd function. Returns SemMuxwaitWait returns the code supplied by the DosWaitMuxWaitSem system directive. See also SemMuxwaitAdd Examples To wait for a muxwait semaphore: call SemMuxwaitWait sem if result \= 0 then signal SemWaitError ΓòÉΓòÉΓòÉ 6.22. SemStartTimer function ΓòÉΓòÉΓòÉ Syntax rc = SemStartTimer([ handleVar ], interval, semHandle, [ type ]) Description SemStartTimer is used to create and start a timer which will post a shared event semaphore. Arguments handleVar is the name of a variable which is to receive the handle to the timer. interval is the time interval in milliseconds. semHandle is a shared event semaphore handle as obtained from SemEventCreate or SemEventOpen. type is the timer type. It must be one of the following keywords: Repeat the timer will repeat; Single the timer will execute only once; this is the default. The keywords are case insensitive and may be abbreviated. Returns SemStartTimer returns the code supplied by the DosAsyncTimer or DosStartTimer system directive. Notes If the return code is non-zero, handleVar is not created or modified. See also SemStopTimer, SemEventCreate, SemEventWait Examples To start a timer and wait until it fires (60 seconds): call SemEventCreate 'timerSem', 'Shared' if result \= 0 then signal SemCreateError call SemStartTimer , 60 * 1000, timerSem if result \= 0 then signal TimerStartError call SemEventWait timerSem if result \= 0 then signal SemWaitError ΓòÉΓòÉΓòÉ 6.23. SemStopTimer function ΓòÉΓòÉΓòÉ Syntax rc = SemStopTimer(timerHandle) Description SemStopTimer is used to stop a timer started with SemStartTimer. Arguments timerHandle is the handle created by SemStartTimer. Returns SemStopTimer returns the code supplied by the DosStopTimer system directive. See also SemStartTimer